home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Cream of the Crop 1
/
Cream of the Crop 1.iso
/
PROGRAM
/
TPP112.ARJ
/
TPP.DOC
< prev
next >
Wrap
Text File
|
1992-04-18
|
19KB
|
445 lines
----------------------------------------------------------------------
04/18/92 Turbo Pascal Pre-Processor All Rights Reserved
Copyright (c) 1991-1992 by SupremeSoft Version 1.12
----------------------------------------------------------------------
Introduction
------------
What is TPP? TPP is a pre-processor designed to work with Turbo Pascal.
Many programmer's who are both C and Pascal programmers find that they
miss C's pre-processing capabilities.
In addition, professional Pascal programmers find it quite absurd to
declare constants for such mundane things as maximum values for array
indexes. This adds to the programs code size, as well as wasting precious
memory. Why declare a constant when you'll only be using it as a fixed
value, which the compiler can determine at compile-time as it is?
In C, all you need to do is use the pre-processor to define this
value. (The question of why use constants at all comes up. Especially if
they are useful, but wasteful of resources. Most languages use constants,
whereas C and C++ provide macro equivalents, and thus have no constant
keywords)
Finally, Turbo Pascal has a gotcha for all constants. They sit in your
data segment. Turbo Pascal, though smart in some ways, is not smart
enough to know that this constant is only a "hard coded" value, and will
thus not replace all references for that constant with its definition.
Besides this, there is a big caveat for using constants as initializers.
Reading your Turbo Pascal manual carefully, you will see that any constant
is only initialized ONCE. Even if it is declared in a procedure, it is only
initialized ONCE, and lives in the data segment and NOT the procedures local
call stack!
In comes TPP. TPP will take your simple constants and replace all
occurrences of that constant with its definition. Besides that, TPP can
be used to abbreviate coding declarations which will later be expanded at
compile time.
-----------------
How to use TPP
-----------------
TPP was designed to allow you to use the same source code that you would
normally use, but also allow you to use TPP keywords. In addition, TPP
works exactly like the Turbo Pascal Compiler. It will not recompile units
that do not need to be. (Although, it is not as smart as the Turbo
compiler as you will see later)
TPP scans your source, looking for a {#DEFINE} statement. This is the
signal to TPP that a macro definition is about to start. After this comes
the regular constant definition. For example:
Normal source: Const
UpperLimit = 3; {This is the upper limit}
LowerLimit = -1; {This is the lower limit}
To adapt to TPP: Const
{#DEFINE} UpperLimit = 3; {This is the upper limit}
{#DEFINE} LowerLimit = -1; {This is the lower limit}
Using this {#DEFINE} statement, your source will compile under Turbo as
usual, but can also be compiled using TPP. You do not need to keep two
different sets of source code.
That is all there is to it. Now, every occurrence of UpperLimit will be
replaced by a "3". You can also define string constants etc. In short any
constant that will work for the Turbo compiler will work for TPP.
Initialized constants, will *NOT* work in TPP, and should be avoided
during regular use of the Turbo compiler. Initialized constants have
numerous flaws and many, many gotchas. (Contact us for more detailed
information on why not to use initialized constants) For example, the
following is *NOT* legal for TPP:
Const
{#Define} LowerLimit : Byte = -1; {This is the lower limit}
You may use TPP to ease your coding a bit, by using the TPP macro feature
as you would normal text macros. For instance:
{#DEFINE} DOS = Intr(21h);
Then, in your code, you may say: DOS; {Call DOS}
and TPP will change this to : Intr(21h); {Call DOS}
Note that TPP can thus be used for other things than just constants!
{#DEFINE} statements may be used anywhere in your source code.
And of course, TPP is not case sensitive.
-------------
Limitations
-------------
TPP is not like the C macro pre-processor. You may not pass variables in
or out, nor do arithmetic expressions. For example, the following are
accepted, but are probably not what you want the macro to do:
1. {#DEFINE} TWICE(X) = X*X;
2. {#DEFINE} HIGH(X) = Odd(X) < Even (X);
3. {#DEFINE} Limits = 32 * MaxValue;
For definition 1, you would need to have a statement of: TWICE(Z);
Expansion then becomes: X*X;
You probably want: Z*Z;
For definition 2, you would need to have a statement of: HIGH(Z);
Expansion then becomes: Odd(X) < Even(X);
You probably want: Odd(Z) < Even(Z);
For definition 3, you would need to have a statement of: Limits;
Expansion then becomes: 32 * MaxValue;
Note: This is not evaluated at macro definition time, unlike in C.
However, Turbo will usually evaluate it at compile-time, so this
is actually a GOOD use for TPP.
You must be careful not to have the macro name anywhere else
in your source code, or else it will get expanded. (That is rather
obvious)
If you use the Const feature of TPP, be careful of the following:
Const
{#DEFINE} UpperLimit = 3; {This is the upper limit}
{#DEFINE} LowerLimit = -1; {This is the lower limit}
Type
.
.
When TPP processes your file, everything but the comments will be
stripped out, leaving:
Const
{This is the upper limit}
{This is the lower limit}
Type
.
.
The Turbo compiler, will *NOT* accept this. There must be something
following the CONST declaration. Be aware of this problem. The only real
work around is to comment out the CONST statement. (This may changed
in later versions of TPP)
-------------
How TPP works
--------------
TPP will scan your source file looking for {#DEFINE} statements or macro
names. It handles Units just like the Turbo compiler, and looks for a
USES keyword. If it finds one, it suspends processing of the current file
and looks at the last file in the USES list. (Just as the Turbo compiler
does) If the TPU for that file is older than the file, TPP will process
that file. This is done for all Units in the USES list.
You may define a macro in one unit, and use it in another, as long as
that unit is listed in the second file's USES list. Confused? Follow the
same programming style as you do regularly. TPP needs no change in
programming! It will allow you to treat your source the same way as Turbo
does. Consider the following:
Unit 1;
...
{Not the next line can be in either the interface OR the implementation
section. Either way it will be visible to other units using this unit}
{#DEFINE} Upper = 99;
Unit 2;
Uses Unit 1;
...
Var t : array[1..Upper] of real;
Even though Unit2 doesn't declare Upper, it can still use it.
------------------------------------------------------------------
One major flaw in TPP:
If Unit1 does NOT need re-compiling, then the macro Upper will never
get defined for TPP!
-------------------------------------------------------------------
Once TPP encounters a macro, it stores the macro name, and its
corresponding definition. In all later files, any time the macro name is
detected, it will get replaced with the definition. Once TPP reads the
macro, it will remove it from the source file. Thus causing the Turbo
compiler to "ignore" the macro, since it isn't there.
TPP will scan all the files needed, but will only produce a new file if
any changes are made to the original source. Depending on the mode of
operation, this new file will either overwrite the original source file,
be named DUM?.PAS or will be erased once the program terminates.
Once TPP completes pre-processing the main file and all of its
corresponding units, it will invoke the Turbo Pascal compiler. Turbo will
then work with the TPP processed files and any others it needs.
TPP will report on the number of lines it has processed, and the time it
took to complete the processing. You should find that TPP blazes through
your files, and only slows once it encounters a macro definition, or a
macro expansion.
----------
Specifics
----------
Calling Syntax: TPP filename[.PAS] [/O | /N | /E] [Turbo Options]
Where: /O Indicates overwrite source files
/N Indicates no compile after processing
/E Indicates execute an editor BEFORE Turbo compiles
Turbo Options are any Turbo Pascal options you wish to
use and they are passed directly on to the compiler.
You may opt to leave off the PAS extension, TPP will add it.
The filename *MUST* be in the current directory, otherwise
the program will abort immediately. (Other files may be anywhere)
More: If you are compling the program, TPP will need to create a
temporary directory to store the TPP processed files. It
is called TPPT, and exists off the current directory.
If you use the /E option then TPP will invoke either the editor
specified in the EDITOR environment variable, or a default
editor of Q.EXE (The Qedit editor) BEFORE it calls the Turbo
compiler. The editor is passed a command line of: *.PAS, and
thus you may edit all of the TPP processed files. Note that
only the TPP processed files will be available in the TPPT
directory. If a file does not get changed by TPP, there is
no need to make a new copy of it.
Why would you want to call an editor? Well, if you know that
a file will have illegal syntax after being processed by TPP,
you can go an correct these errors. Tpyically, once TPP has
stripped a file of all constants, you are left with a CONST
keyword, but no definitions. Turbo doesn't like this, and
executing the editor before compiling allows you to remove
all the CONST keywords.
Once compilation completes, all TPU and EXE files will be
moved to the original directory. If the /O option is
specified, then all PAS files will be moved back as well.
If you are not compiling, and have not specified the /O
option, then you will be left with some DUM?.PAS files,
where ? indicates an integer value. These are the TPP
processed files.
If you specify the /O option, then the original source
files will be renamed to BAK files, and the TPP processed
will be named to the original source files.
When the Turbo compiler is invoked, TPP will attempt to
swap out to disk or EMS. If successful, only 1.5K of TPP
will be left in memory. If it cannot swap out, it attempts
to free up as much memory as it can. This allows TPC to
have as much memory available as possible.
When invoked, TPC will be passed the following:
TPC /M filename [Turbo Options]
Note that it will always be invoked using the /M option!
Returns: The DOS ERRORLEVEL return code will be set as follows:
1 Help screen invoked
2 File error occurred
3 Out of memory error
4 File not in current directory
This may be useful in batch files, or in a MAKE utility.
-------------------------
How does TPP find files?
--------------------------
TPP will attempt to find and read TPC.CFG in order to find out where all
your source files are located. If it cannot find the source file in the
current directory, it will then scan the Unit directories listed in
TPC.CFG. It will *NOT* look on your PATH!
ReadOnly files are valid, and will be processed correctly.
------------------------
Errors and Memory issues
------------------------
How much memory does TPP use? That depends on how many macros you define,
how many unit dependencies you have, and the size of your source.
Typically, TPP can process up to 50,000 lines in as little as 100K, with
300 macros defined.
Upon a memory error, TPP will give you a standard "Out of memory" error.
If this happens, you will have to remove some TSR's to make room. But be
aware of this, if TPP cannot complete, there is no way TPC will ever be
able to compile, since it too will usually run out of memory.
Upon a file error, TPP will issue a message, asking you to either abort
or continue. If you abort, you will be asked to confirm it. Then an error
code will be output, which is the standard IORESULT that any Turbo program
issues. Look it up in the programmers reference manual. If it is a file
error, you've got a problem. If it's some other error caused by TPP,
*please let us know*!
----------
Warnings
----------
Under no circumstances have the word USES anywhere before your actual
USES statement. TPP is not a compiler, and will treat a USES within a
comment block to be the keyword it wants. Any time after the original
USES statement, TPP will ignore the word. Thus, this should NOT happen:
Unit Test;
{This unit uses two dependencies}
Interface
Uses DOS,CRT;
But, this is legal:
Unit Test;
{This is a test unit}
Interface
Uses DOS,CRT;
{This unit uses two dependencies}
When TPP is run in compilation mode, it needs to create the directory
TPPT. IF this already exists, you are asked if you wish to use it or not.
If you answer yes, be aware that if any files already exist in this
directory, TPP will *NOT* overwrite them with new copies. Why? Usually,
the copies in those directories are identical to the ones about to
overwrite them. Thus, to save time, TPP reports an error, but does not
abort operation.
The question comes up, when do I use TPP? Do I develop with it? The
answer is no. Since TPP lets you use the same source code, develop, test
and debug using your normal methods. But when it comes time to do a
production version, run TPP.
Of course, if you are using the macro expansion capabilities, then you
must use TPP all the time. TPP is not memory resident, and does not
interface with the Turbo compiler. Therefore, you must use the command
line compiler. (And no, there are no plans to develop a sophisticated TSR
version...)
TPP is very fast. It doesn't need to do all that much, but it is a good
idea to have a nice sized disk cache in place, since a lot of disk
activity will be apparent. Besides, the Turbo compiler will also be given
a boost.
-----------------
Savings using TPP
-----------------
How much do you *really* save using TPP? Honestly, that depends on how
many CONSTANTs you have in any program. If you program correctly, there
should be very few, and thus the code size savings are minimal and
probably not worth it unless you are having a code size contest. Code
size is hardly affected because now you are substituting a memory
location for a hard coded value, but the instruction is still coded.
Thus, the only savings comes from TPP's constant folding and other
optimizations.
So code size is not a major factor. But memory size is! By using TPP you
save the memory space needed for all those constants that are being held
in memory by Turbo Pascal. The more you have, the more you save. This
should become apparent immediately.
By using the enhanced macro expansion capability of the program, you
might save some code and memory space, but not much. However you save on
coding time, another important development factor.
-----------------------------------------------------------------
Warranty and License:
-----------------------------------------------------------------
There is NO warranty either expressed or implied. SupremeSoft can
not be held accountable for anything resulting from the use, or misuse,
of this program. Your use of this program acknowledges the fact that you
understand that you are using this program of your own free will, and
will take any consequences resulting from that action and cannot hole
SupremeSoft responsible for any reason.
You are granted a limited license of 30 days to evaluate this
program. Should you use it beyond that period, you must register your
copy, or else be in violation of this license agreement. To register,
send $15.00 to the address below:
Send a check/money order to the following address:
SupremeSoft
105 Deerfield Drive
Easton, CT 06612
Re: TPP (1.12)
You may also contact: msingh@ucs.indiana.edu if you have access to the
Internet. You can report bugs, problems, pains, antecdotes, etc.
----------------------
Registration benefits
----------------------
TPP will annoy Shareware users. There is an opening random delay, up to 9
seconds, and there is another delay at the end of the program, before
you are returned to DOS. (But not before TPC is executed)
Why? It has been our experience that the Shareware concept doesn't work
as well if one offers no limitations on the program. Thus, rather than
leaving out features, annoyances are introduced. A lot of time has gone
into the development of this program, and we feel that users should pay
for the program if it is of any use to them.
Registered users have no delay's, or requests for key presses. In
addition, at the time of registration we will send you the absolute
latest version of the program. After receipt of the program, you may send
us a SASE disk mailer and receive the next update for free, for the life
time of the program's development. That's right, for free, as long as you
pay for postage and provide a mailer.